<TeXmacs|1.99.16>

<project|rehash.tm>

<style|<tuple|tmmanual|british>>

<\body>
  Downloads are performed asynchronuously. The operations defined below are
  synchronuous, however, so they return when the underlying C operations are
  completed.

  <subsection|Status control>

  <\explain>
    <scm|(download-start! <scm|filesharing> <scm-arg|uri> #:filename
    #:anonymity #:offset #:length #:callback
    #:no-network?)><explain-synopsis|Download a part of a file>
  <|explain>
    Asynchronuously start to download a part of a file <var|uri>. The part to
    download is specified by an offset <var|offset> and the length
    <var|length> of the part to download. The downloaded part will be written
    to <var|filename> at the requested <var|offset>. Note that slightly more
    bytes may actually be downloaded, so the download may be slightly out of
    bounds. The following keyword arguments are permitted:

    <\description>
      <item*|<var|offset>>Offset (in bytes) to download at into the resource
      identified by <var|uri>. Also the corresponding offset into the file
      with name <var|filename> to write to. Defaults to 0. This must be an
      exact natural number. Due to implementation limitations, this must be
      <math|\<nosymbol\>\<less\>2<rsup|64>>.

      <item*|<var|length>>Length (in bytes) of the part to download. This
      must be an exact natural number. Due to implementation limitations,
      this must be <math|\<nosymbol\>\<less\>2<rsup|64>>. By default, this is
      the size of the resource at <var|uri>, minus <var|offset>.

      <item*|<var|anonymity>>Anonymity level, see GNUnet documentation for
      specifics. This is an exact natural number
      <math|\<nosymbol\>\<less\>2<rsup|32>>. By default, basic level of
      anonymity is requested.

      <todo|perhaps use a parameter for defaults>

      <item*|<scm|no-network>?>A boolean, defaults to <scm|#f>. If true, only
      search locally without asking other peers.

      <item*|<var|callback>>Optional, set to <scm|#f> to explicitly disable.
      This will register a progress callback for the download, directly after
      its creation (without any race conditions). This callback registration
      will not be garbage collected, and cannot be removed.

      <item*|<var|filename>>Name of the file to write the downloaded part to.
      <todo|with whose authority is <var|filename> written to? The caller,
      the FS service?>
    </description>

    <todo|parent>
  </explain>

  <\explain>
    <scm|(download-stop! <scm-arg|download>
    <scm-arg|#:delete-incomplete>)><explain-synopsis|Stop a download>
  <|explain>
    Stop a download <var|download>. This has no effect if <var|download> is
    stopped already. This effectively frees <var|download> (in the C sense),
    so <var|download> will not be useful in the future.

    <todo|Different from the C API, this may be called from a callback (in
    which case the actual abort will be delayed somewhat) TODO was this only
    for FS_stop, or also for FS_download_stop>

    If the optional keyword argument <var|#:delete-incomplete> is set to
    <scm|#t>, then the file downloaded to will be deleted if the download was
    incomplete.
  </explain>

  <\explain>
    <scm|(download-suspend! <scm-arg|download>)> <explain-synopsis|(Suspend a
    download)>
  </explain|Suspend a download <var|download>. This has no effect
  <var|download> already is suspended. In case <var|download> is stopped,
  raise a <scm|&closed-download> instead. The download can be resumed with
  <scm|download-resume!>.>

  <\explain>
    <scm|(download-resume! download)><explain-synopsis|Resume a download>
  </explain|Resume a download <var|download>. In case download is stopped,
  raise a <scm|&closed-download> instead.>

  <subsection|Notifications>

  These are convenience procedures, the event callbacks should suffice in
  theory.

  <\explain>
    <scm|(download-completed-operation <scm-arg|download>)><explain-synopsis|Operation
    waiting until download is completed>
  </explain|When the download <var|download> is completed, return no values.>

  <\explain>
    <scm|(download-stopped-operation <scm-arg|download>)><explain-synopsis|Operation
    waiting until download is stopped>
  <|explain>
    When the download <var|download> is stopped, return no values.

    <todo|does this include completion, errors, ???>
  </explain>
</body>

<\initial>
  <\collection>
    <associate|save-aux|false>
  </collection>
</initial>